{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# hvPlot.hexbin\n",
    "\n",
    "```{eval-rst}\n",
    ".. currentmodule:: hvplot\n",
    "\n",
    ".. automethod:: hvPlot.hexbin\n",
    "```\n",
    "\n",
    "## Backend-specific styling options\n",
    "\n",
    "```{eval-rst}\n",
    ".. backend-styling-options:: hexbin\n",
    "```\n",
    "\n",
    "## Examples\n",
    "\n",
    "### Basic hexbin plot"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "import pandas as pd\n",
    "import numpy as np\n",
    "\n",
    "df = pd.DataFrame({\n",
    "    \"x\": 2 + 2 * np.random.standard_normal(10000),\n",
    "    \"y\": 2 + 2 * np.random.standard_normal(10000),\n",
    "})\n",
    "\n",
    "df.hvplot.hexbin(aspect=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Basic 2D density with earthquake locations\n",
    "\n",
    "This example shows how to use hexbin to visualize the spatial density of earthquake events based on latitude and longitude."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas # noqa\n",
    "\n",
    "df = hvplot.sampledata.earthquakes(\"pandas\")\n",
    "\n",
    "df.hvplot.hexbin(\n",
    "    x=\"lon\", y=\"lat\", cmap=\"plasma\",\n",
    "    data_aspect=1, xlim=(120, 130), ylim=(0, 10)\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Aggregate with a specific variable and function\n",
    "\n",
    "In this example the hexbin is colored by the aggregated mean depth, set with the keywords `C` and `reduce_function`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "import numpy as np\n",
    "\n",
    "df = hvplot.sampledata.earthquakes(\"pandas\")\n",
    "\n",
    "df.hvplot.hexbin(\n",
    "    x=\"lon\", y=\"lat\", cmap=\"plasma\",\n",
    "    data_aspect=1, xlim=(120, 130), ylim=(0, 10),\n",
    "    C='depth', reduce_function=np.mean, clabel='Mean depth',\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Display threshold and grid size\n",
    "\n",
    "Increasing `min_count` (default is 1) reduces the number of hexagonal cells plotted."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "import numpy as np\n",
    "\n",
    "df = hvplot.sampledata.earthquakes(\"pandas\")\n",
    "\n",
    "df.hvplot.hexbin(\n",
    "    x=\"lon\", y=\"lat\", cmap=\"plasma\", data_aspect=1,\n",
    "    frame_width=300, xlim=(120, 130), ylim=(0, 10),\n",
    "    min_count=1, title='min_count=1',\n",
    ") +\\\n",
    "df.hvplot.hexbin(\n",
    "    x=\"lon\", y=\"lat\", cmap=\"plasma\", data_aspect=1,\n",
    "    frame_width=300, xlim=(120, 130), ylim=(0, 10),\n",
    "    min_count=3, title='min_count=3',\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Increasing `gridsize` (default is 50) increases the number of hexagonal cells plotted. The number of cells in the x and y directions can be customized by setting `gridsize` with a tuple."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "import numpy as np\n",
    "\n",
    "df = hvplot.sampledata.earthquakes(\"pandas\")\n",
    "\n",
    "df.hvplot.hexbin(\n",
    "    x=\"lon\", y=\"lat\", cmap=\"plasma\", data_aspect=1, frame_width=300,\n",
    "    gridsize=10, title='gridsize=10',\n",
    ") +\\\n",
    "df.hvplot.hexbin(\n",
    "    x=\"lon\", y=\"lat\", cmap=\"plasma\", data_aspect=1, frame_width=300,\n",
    "    gridsize=(20, 50), title='gridsize=(20, 50)',\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Xarray example\n",
    "\n",
    "This example aggregates temperature readings across longitudes and latitudes using hexagonal bins. `logz=True` applies a logarithmic color scale, and `gridsize` controls hex resolution."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.xarray  # noqa\n",
    "import numpy as np\n",
    "\n",
    "da = hvplot.sampledata.air_temperature(\"xarray\").sel(time=\"2014-02-25 12:00\")\n",
    "\n",
    "da.hvplot.hexbin(\n",
    "    x=\"lon\", y=\"lat\", cmap=\"inferno\",\n",
    "    bgcolor=\"#020210\", data_aspect=1, frame_width=400,\n",
    "    C=\"air\", reduce_function=np.mean, clabel=\"Air temperature (K)\",\n",
    "    logz=True, gridsize=30,\n",
    ")"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
